home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 November: Tool Chest / Dev.CD Nov 98 TC.toast / Sample Code / Networking / GetPPPStatus / headers / AEHelpers.h next >
Encoding:
Text File  |  1998-02-06  |  13.1 KB  |  407 lines  |  [TEXT/CWIE]
  1. /*
  2. **    Apple Macintosh Developer Technical Support
  3. **
  4. **    Functions to help you when you are building and sending Apple events.
  5. **
  6. **    by Andy Bachorski, Apple Developer Technical Support
  7. **
  8. **    File:        MoreFinderEvents.h
  9. **
  10. **    Version:    0.3.5
  11. **
  12. **    Copyright © 1996 Apple Computer, Inc.
  13. **    All rights reserved.
  14. **
  15. **    You may incorporate this sample code into your applications without
  16. **    restriction, though the sample code has been provided "AS IS" and the
  17. **    responsibility for its operation is 100% yours.  However, what you are
  18. **    not permitted to do is to redistribute the source as "DSC Sample Code"
  19. **    after having made changes. If you're going to re-distribute the source,
  20. **    we require that you make it clear in the source that the code was
  21. **    descended from Apple Sample Code, but that you've made changes.
  22. */
  23.  
  24. //
  25. // %%%%% need to change calls to object building function to pass a boolean
  26. // %%%%% parameter to control the disposal of descs passed in.
  27.  
  28. #ifndef AEHELPERS
  29. #define AEHELPERS
  30.  
  31.  
  32. //    Prefix file
  33. #include "Prefix.h"
  34.  
  35. //    System includes
  36. #include <AERegistry.h>
  37. #include <AEObjects.h>
  38. #include <AEPackObject.h>
  39. #include <Aliases.h>
  40. #include <Icons.h>
  41.  
  42.  
  43. #ifdef __cplusplus
  44. extern "C" {
  45. #endif
  46.  
  47.  
  48. // *****************************************************************************
  49.  
  50. PASCAL    OSErr    FindProcessBySignature( const OSType targetType,
  51.                                         const OSType targetCreator,
  52.                                               ProcessSerialNumberPtr psnPtr );
  53.  
  54. /*    The FindProcessBySignature function returns a ProcessSerialNumber
  55.     for a process whose signature (type and creator) matches the input values.
  56.     The ProcessSerialNumber will be kNoProcess is the requested process cannot
  57.     be found. 
  58.  
  59.     targetType        input:    The file type of the process to be found.
  60.     targetCreator    input:    The creator type of the process to be found.
  61.     
  62.     psnPtr            input:    Pointer to a ProcessSerialNumber where the
  63.                             process serial number is returned.
  64.                     output:    Process serial number.
  65.     
  66.     RESULT CODES
  67.     ____________
  68.     noErr               0    No error
  69.     procNotFound    –600    No eligible process with specified descriptor
  70.     ____________
  71. */
  72.  
  73. // *****************************************************************************
  74.  
  75. PASCAL    OSErr    AEHMakeAppleEventSignatureTarget( const OSType targetType,
  76.                                                   const OSType targetCreator,
  77.                                                   const AEEventClass eventClass,
  78.                                                   const AEEventID eventID,
  79.                                                         AppleEvent *theEvent );
  80.  
  81. /*    Create and return an AppleEvent of the given class and ID. The event will be
  82.     targeted at the process specified by the target type and creator codes, 
  83.     with an AEAddressDesc of type typeProcessSerialNumber.
  84.  
  85.     targetType        input:    The file type of the process to be found.
  86.     targetCreator    input:    The creator type of the process to be found.
  87.     eventClass        input:    The class of the event to be created.
  88.     eventID            input:    The ID of the event to be created.
  89.     
  90.     theEvent        input:    Pointer to an AppleEvent record where the
  91.                             event record will be returned.
  92.                     output:    The Apple event.
  93.     
  94.     RESULT CODES
  95.     ____________
  96.     noErr               0    No error    
  97.     memFullErr        -108    Not enough room in heap zone    
  98.     procNotFound    –600    No eligible process with specified descriptor
  99.     ____________
  100. */
  101.  
  102.  
  103. // *****************************************************************************
  104.  
  105. PASCAL    OSErr    AEHMakeEventProcessTarget( const ProcessSerialNumberPtr psnPtr,
  106.                                            const AEEventClass eventClass,
  107.                                            const AEEventID eventID,
  108.                                                  AppleEvent *theEvent );
  109.  
  110. /*    Create and return an AppleEvent of the given class and ID. The event will be
  111.     targeted with the provided PSN.
  112.  
  113.     psnPtr            input:    Pointer to the PSN to target the event with.
  114.     eventClass        input:    The class of the event to be created.
  115.     eventID            input:    The ID of the event to be created.
  116.     
  117.     theEvent        input:    Pointer to an AppleEvent record where the
  118.                             event record will be returned.
  119.                     output:    The Apple event.
  120.     
  121.     RESULT CODES
  122.     ____________
  123.     noErr               0    No error    
  124.     memFullErr        -108    Not enough room in heap zone    
  125.     procNotFound    –600    No eligible process with specified descriptor
  126.     ____________
  127. */
  128.  
  129. // *****************************************************************************
  130.  
  131. PASCAL    OSErr    AEHMakeEventTargetID( const TargetID *targetIDPtr,
  132.                                       const AEEventClass eventClass,
  133.                                       const AEEventID eventID,
  134.                                             AppleEvent *theEvent );
  135.  
  136. // *****************************************************************************
  137.  
  138. PASCAL    OSErr    AEHMakeAliasDescFromFSSpec( const FSSpecPtr fssPtr,
  139.                                                   AEDesc *aliasDesc );
  140.                                                   
  141. /*    Create and return an AEDesc of type typeAlias using the provided FSSpec.
  142.  
  143.     fssPtr            input:    Pointer to the FSSpec to use.
  144.     
  145.     theEvent        input:    Pointer to null AEDesc.
  146.                     output:    an AEDesc of type typeAlias.
  147.     
  148.     RESULT CODES
  149.     ____________
  150.     noErr               0    No error    
  151.     paramErr         -50    The value of target or alias parameter, or of
  152.                             both, is NIL, or the alias record is corrupt
  153.     memFullErr        -108    Not enough room in heap zone    
  154.     ____________
  155. */
  156.  
  157. // *****************************************************************************
  158.  
  159. PASCAL OSErr AEHMakeAliasDesc( const AliasHandle aliasHandle,
  160.                                      AEDesc *aliasDesc );
  161.  
  162. /*    Create and return an AEDesc of type typeAlias using the provided 
  163.     alias record.
  164.  
  165.     fssPtr            input:    Handle to an alias record.
  166.     
  167.     theEvent        input:    Pointer to null AEDesc.
  168.                     output:    an AEDesc of type typeAlias.
  169.     
  170.     RESULT CODES
  171.     ____________
  172.     noErr               0    No error    
  173.     memFullErr        -108    Not enough room in heap zone    
  174.     ____________
  175. */
  176.  
  177.  
  178. // *****************************************************************************
  179.  
  180. PASCAL    OSErr    AEHMakeAliasObjectFromFSSpec( const FSSpecPtr fssPtr,
  181.                                                     AEDesc *containerObj,
  182.                                                     AEDesc *aliasObject );
  183. /*
  184.     Given an FSSpec, return an object descriptor containing an alias,
  185.     contained by a null object.
  186.     
  187.     RESULT CODES
  188.     ____________
  189.     noErr                    0    No error    
  190.     paramErr              -50    The value of target or alias parameter, or of
  191.                                 both, is NIL, or the alias record is corrupt
  192.     memFullErr             -108    Not enough room in heap zone    
  193.     errAECoercionFail     -1700    Data could not be coerced to the requested 
  194.                                 Apple event data type    
  195.     errAEWrongDataType    -1703    Wrong Apple event data type    
  196.     errAENotAEDesc        -1704    Not a valid descriptor record    
  197.     errAEBadListItem    -1705    Operation involving a list item failed    
  198.     ____________
  199. */
  200.  
  201. // *****************************************************************************
  202.  
  203. PASCAL    OSErr    AEHMakeAliasObject( const AliasHandle aliasHandle,
  204.                                           AEDesc *containerObj,
  205.                                           AEDesc *aliasObject );
  206. /*
  207.     Given an object descriptor, create an new object descriptor containing an
  208.     alias, contained by the input object descriptor.
  209.     
  210.     RESULT CODES
  211.     ____________
  212.     noErr                    0    No error    
  213.     paramErr              -50    Error in parameter list
  214.     memFullErr             -108    Not enough room in heap zone    
  215.     errAECoercionFail     -1700    Data could not be coerced to the requested 
  216.                                 Apple event data type    
  217.     errAEWrongDataType    -1703    Wrong Apple event data type    
  218.     errAENotAEDesc        -1704    Not a valid descriptor record    
  219.     errAEBadListItem    -1705    Operation involving a list item failed    
  220.     ____________
  221. */
  222.  
  223. // *****************************************************************************
  224.  
  225. PASCAL    OSErr    AEHMakePropertyObject( const DescType propType,
  226.                                              AEDesc *containerObj,
  227.                                              AEDesc *propertyObj );
  228. /*
  229.     Given an object descriptor, create an new object descriptor containing
  230.     an property, contained by the input object descriptor.
  231.     
  232.     RESULT CODES
  233.     ____________
  234.     noErr                    0    No error    
  235.     paramErr              -50    Error in parameter list
  236.     memFullErr             -108    Not enough room in heap zone    
  237.     errAECoercionFail     -1700    Data could not be coerced to the requested 
  238.                                 Apple event data type    
  239.     errAEWrongDataType    -1703    Wrong Apple event data type    
  240.     errAENotAEDesc        -1704    Not a valid descriptor record    
  241.     errAEBadListItem    -1705    Operation involving a list item failed    
  242.     ____________
  243. */
  244.  
  245. // *****************************************************************************
  246. PASCAL    OSErr    AEHMakeProcessObject( const ProcessSerialNumber *psnPtr,
  247.                                              AEDesc *containerObj,
  248.                                              AEDesc *propertyObj );
  249. // *****************************************************************************
  250.  
  251. PASCAL    OSErr    AEHMakeSelectionObject( const DescType selection,
  252.                                               AEDesc *containerObj,
  253.                                               AEDesc *propertyObj );
  254. /*
  255.     Given an object descriptor, create an new object descriptor containing
  256.     a selection object using the selection specifier, contained by the 
  257.     input object descriptor.
  258.     
  259.     RESULT CODES
  260.     ____________
  261.     noErr                    0    No error    
  262.     paramErr              -50    Error in parameter list
  263.     memFullErr             -108    Not enough room in heap zone    
  264.     errAECoercionFail     -1700    Data could not be coerced to the requested 
  265.                                 Apple event data type    
  266.     errAEWrongDataType    -1703    Wrong Apple event data type    
  267.     errAENotAEDesc        -1704    Not a valid descriptor record    
  268.     errAEBadListItem    -1705    Operation involving a list item failed    
  269.     __________
  270. */
  271.  
  272. // *****************************************************************************
  273. PASCAL    OSErr    AEHMakeIconSuite( const AEDescList *iconFamilyRecPtr,
  274.                                         Handle *iconSuitePtr );
  275. // *****************************************************************************
  276.  
  277. PASCAL    OSErr    AEHMakeIconFamilyRecord( const Handle iconSuite,
  278.                                          const IconSelectorValue iconSelector,
  279.                                                AEDescList *iconFamilyRecPtr );
  280.  
  281. /*    ¶ Make an icon family record containing the icons specified in the
  282.     iconSelector parameter.
  283.     The iconSuite parameter should contain an icon suite, as returned by a
  284.     call to GetIconSuite.
  285.     
  286.     iconSuite            input:    The icon suite to build the record from.
  287.     iconSelector        input:    Which icons to include in the record.
  288.     iconFamilyRecPtr    input:    A null descriptor record.
  289.                         output:    An AERecord that's been coerced to an
  290.                                 icon family record.
  291.     
  292.     Result Codes
  293.     ____________
  294.     noErr                    0    No error    
  295.     paramErr              -50    The value of target or alias parameter, or of
  296.                                 both, is NIL, or the alias record is corrupt
  297.     memFullErr             -108    Not enough room in heap zone    
  298.     errAECoercionFail     -1700    Data could not be coerced to the requested 
  299.                                 Apple event data type    
  300.     ____________
  301.     
  302.     Also see:
  303. */
  304.  
  305. // *****************************************************************************
  306.  
  307. PASCAL    OSErr    AEHGetHandlerError( const AppleEvent *reply );
  308. /*
  309.     Given a reply event, checks for errors returned by the event handler,
  310.     and returns any that are found.
  311.     
  312.     reply                input:    The reply event to be checked.
  313.  
  314.     RESULT CODES
  315.     ____________
  316.     noErr                    0    No error    
  317.     paramErr              -50    The value of target or alias parameter, or of
  318.                                 both, is NIL, or the alias record is corrupt
  319.     memFullErr             -108    Not enough room in heap zone    
  320.     errAECoercionFail     -1700    Data could not be coerced to the requested 
  321.                                 Apple event data type    
  322.     errAEWrongDataType    -1703    Wrong Apple event data type    
  323.     errAENotAEDesc        -1704    Not a valid descriptor record    
  324.     errAEBadListItem    -1705    Operation involving a list item failed
  325.     
  326.     ????                Pretty much any error, depending on what the handler
  327.                         of the event sent does.
  328.     ____________
  329. */
  330.  
  331. // *****************************************************************************
  332.  
  333. PASCAL    Boolean    AEHSimpleIdleFunction( EventRecord *event,
  334.                                       long *sleepTime,
  335.                                       RgnHandle *mouseRgn );
  336. /*
  337.     A very simple idle function. It simply ignors an event it receives,
  338.     returns 30 for the sleep time and nil for the mouse region.
  339.     
  340.     Your application would normally supply a more robust idle function,
  341.     especially if you have any window. See the tech note on Pending Update
  342.     Perils.
  343. */    
  344.  
  345. // *****************************************************************************
  346.  
  347. PASCAL    Boolean    HasAppleEvents( void );
  348. /*
  349.     Calls Gestalt and checks if the Apple Event Manager is available.
  350.     
  351.     Use this routine together with FinderCallsAEProcess to determine which
  352.     suite of events the Finder supports. If FinderCallsAEProcess returns false
  353.     the Finder supports the subset of the older Finder event suite.
  354.  
  355.     RESULT CODES
  356.     ____________
  357.     true    The Apple Event Manager is present
  358.     false    It isn't
  359. */
  360.  
  361. // *****************************************************************************
  362.  
  363. PASCAL    Boolean    FinderCallsAEProcess( void );
  364. /*
  365.     Calls Gestalt and checks if the Finder calls AEProcessAppleEvent.
  366.     If true, the Finder is version 7.1.3 or later.
  367.     
  368.     Use this routine together with FinderIsOSLCompliant to determine which
  369.     suite of events the Finder supports. If FinderIsOSLCompliant returns false
  370.     the Finder supports the full older Finder event suite.
  371.     
  372.     RESULT CODES
  373.     ____________
  374.     true    The Finder calls supports the full old Finder event suite
  375.     false    It doesn't
  376. */
  377.  
  378. // *****************************************************************************
  379.  
  380. PASCAL    Boolean    FinderIsOSLCompliant( void );
  381. /*
  382.     Calls Gestalt and checks if the Finder is OSL compliant, i.e., it supports
  383.     the new Finder event suite.
  384.     
  385.     If true, the Finder is version 7.5 or later. This means the Finder supports,
  386.     and that you should use, the new Finder event suite. It also means that 
  387.     support for the events present in old Finder event suite is either missing
  388.     or incomplete.
  389.         
  390.     RESULT CODES
  391.     ____________
  392.     true    The Finder supports the new Finder event suite, not the old
  393.     false    It doesn't
  394. */
  395.  
  396. // *****************************************************************************
  397.  
  398. #ifdef __cplusplus
  399. }
  400. #endif
  401.  
  402. #ifndef COMPILING_MORE_FINDER_EVENTS
  403.     #undef PASCAL
  404. #endif
  405.  
  406. #endif// AEHELPERS
  407.